Request for Comments: xxxx R. E. Moore FYI: xx IBM Networking Systems April 1995 SNMP over SNA using APPC Status of this Memo This document is being distributed for review by the AIW. It will be discussed at the SNMP over SNA BOF at AIW7. Abstract This memo defines a mechanism for carrying SNMP protocol data units on an SNA network using APPC sessions. In addition to the transport mapping itself, there is also a description of how the mechanism would be deployed and used in an Advanced Peer-to-Peer Networking (APPN) network. The architecture is specified by indicating the calls that an application makes to the Common Programming Interface for Communications (CPI-C) version 2.0. Table of Contents 1.0 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2.0 Specifics of the Design . . . . . . . . . . . . . . . . . . . 2 2.1 APPC Parameters . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.1 Destination LU Name . . . . . . . . . . . . . . . . . . . 3 2.1.2 Partner TP Name . . . . . . . . . . . . . . . . . . . . . 3 2.1.3 Mode Name . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 Structure of the APPC Data . . . . . . . . . . . . . . . . . . 4 2.3 SNMP PDUs . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.0 SNMP over SNA in an APPN Network . . . . . . . . . . . . . . . 7 4.0 Overview of the CPI-C TPs for SNMP over SNA . . . . . . . . . 9 4.1 Sending Side . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.2 Receive Side . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.0 References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6.0 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 12 1.0 Overview Advanced Program-to-Program Communication (APPC) is an SNA framework for communication involving a pair of transaction programs. Communication is initiated by a transaction program assuming the client role for the duration of the communication; the partner transaction program assumes the server role. Once it has been started, an instance of communication Moore [Page 1] RFC xxxx SNMP over SNA April 1995 (termed a "conversation" in APPC) may go on for a long period of time, and involve many exchanges of information between the communicating transaction programs. For SNMP data, however, a long-lived conversation is not necessary. In fact, such a design would introduce difficulties for SNMP applications: because they are currently predicated on UDP datagrams as the vehicle that transports SNMP information, they can be designed with very simple logic for error recovery. Basically, SNMP applications today need to be tolerant of the loss of SNMP data, but they need not worry about any clean-up or reset of the mechanism that actually delivers the data. With long-lived conversations, SNMP applications would have to worry about clean-up of their APPC sessions; for example, a manager would have to determine when to release the conversation on which it had sent an SNMP GET operation, if no response to the GET ever came back from the agent. The basic design for transporting SNMP data over SNA closely resembles that for SNMP over UDP. SNA logical units (LUs) correspond to the IP hosts, APPC transaction programs (TPs) to the UDP ports, and registered APPC transaction programs to the well-known UDP ports. TPs with user-defined names can also participate in SNMP over SNA communications, either with registered TPs or with other TPs with user-defined names. By default, however, SNMP over SNA communication involves the registered TPs. When a UDP datagram is delivered, the sender's UDP port is identified in the UDP header. Thus it is easy for an SNMP agent to send its response back to the (application at the) UDP port that sent it a request. APPC does not provide the analogous service to a receiving TP, i.e., it does not identify the sending TP in the APPC header. To make it possible for an SNMP agent to respond back to the TP that sends it a request, therefore, it is necessary to carry the sending TP's name alongside the SNMP PDU in the APPC data. Each SNMP PDU to be sent results in only a single network flow between the sending and receiving LUs. The information to bring up a new conversation, transport a unit of data on the conversation, and then take the conversation down, all flows in a single APPC Request Unit (RU). The preceding sentence assumes that the underlying session that will carry the conversation is already in place. If startup of the session is necessary, that will involve additional network flows. In the case of SNMP over SNA, the underlying sessions will ordinarily be in place, and remain in place, so the additional flows will not ordinarily be required. 2.0 Specifics of the Design Moore [Page 2] RFC xxxx SNMP over SNA April 1995 2.1 APPC Parameters In order to initiate a conversation with a partner transaction program (TP), a CPI-C TP needs to supply three pieces of information: o The network-qualified LU name of the destination o The partner's TP name o A mode name, indicating the type of session to be used. These three pieces of information are discussed in the following sections. 2.1.1 Destination LU Name This is a two-level SNA name, consisting of: o A one- to eight-character SNA network identifier o A period ('.') to serve as a delimiter o A one- to eight-character LU name. The destination LU name indicates which SNA resource the SNMP information is being directed to. For an agent sending an SNMP trap, the identity of the trap receiver is determined based on mechanisms outside this architecture. Ordinarily this information will be configured at the agent. For an SNMP manager sending operations to agents, the identities of the agents may be configured, or they may be discovered by SNA-specific means. See 3.0, "SNMP over SNA in an APPN Network" on page 7. 2.1.2 Partner TP Name APPC supports two types of transaction program names: registered and unregistered. A registered TP name is represented as a hexadecimal value. It is distinguishable from an unregistered name by having a value in its first byte less than or equal to X'3F'. Registered TP names are assigned to specific transaction programs by the SNA architecture; thus there is no chance of their colliding accidentally with the names of other TPs. By default, SNMP over SNA uses the following four registered TP names: X'23F0F0F3' The TP at an SNMP manager that sends an SNMP request to an agent. This will be the destination TP for the response. It is identified in the registry as the "SNMP_PORT_00160_registered" transaction program. X'23F0F0F4' The agent TP to which a manager sends an SNMP request. This TP corresponds to the well-known UDP port 161. It is identified in the registry as the "SNMP_PORT_00161_registered" transaction program. Moore [Page 3] RFC xxxx SNMP over SNA April 1995 X'23F0F0F5' The TP at an SNMP manager to which an agent sends a trap. This TP corresponds to the well-known UDP port 162. It is identified in the registry as the "SNMP_PORT_00162_registered" transaction program. X'23F0F0F6' The TP at an SNMP agent that sends a trap. This will be the destination TP for the inform confirming receipt of the trap. It is identified in the registry as the "SNMP_PORT_00163_registered" transaction program. In addition to these four registered TP names, there is a format for unregistered names that is recommended for use in situations where the registered TP names are not sufficient. (One such situation is when multiple SNMP managers or agents are installed on the same LU, for development, testing, or migration.) These names have the following form: SNMP_PORT_ppppp[_ccc...ccc] where "ppppp" represents in EDCDIC a five-digit decimal port number, padded with EBCDIC 0's (X'F0' characters) on the left (if necessary), and "ccc..ccc" indicates an optional EBCDIC character string of up to 48 characters. Examples of names with this structure include "SNMP_PORT_01234_testing" and "SNMP_PORT_01234_production". All unregistered TP names are encoded in EBCDIC using coded graphic character set 00640-00500. See [1] for details. 2.1.3 Mode Name By default, SNMP over SNA uses sessions with the mode name SNASVCMG for sending requests and traps. These sessions were chosen because (1) they are already in place in most SNA environments, and (2) the traffic they currently carry fits in well with the SNMP data that will be flowing between the SNMP TPs. Once again, see 3.0, "SNMP over SNA in an APPN Network" on page 7 for more details. A manager sending a request, or an agent sending a trap, may specify a mode name other than SNASVCMG. To maximize interoperability, an agent specifies the same mode name for a response that the manager specified on the operation to which the agent is responding. 2.2 Structure of the APPC Data APPC data is encoded using length-delimited structures termed Generalized Data Stream (GDS) variables. A GDS variable has a two-byte length, a two-byte key, and a variable number of bytes of data. The data that flows between the SNMP over SNA TPs is structured as follows: Moore [Page 4] RFC xxxx SNMP over SNA April 1995 X'xxxx' length of X'1222' GDS X'1222' key of X'1222' GDS X'xxxx' length of X'FF00' structured field X'FF00' key of X'FF00' structured field X'xx' length of X'00' subfield X'00' key of X'00' subfield data in X'00' subfield X'xxxx' length of X'FF01' structured field X'FF01' key of X'FF01' structured field data in X'FF01' structured field All of the lengths include the length bytes themselves. The length of the X'1222' GDS variable includes the two structured fields nested inside of it. Similarly, the length of the X'FF00' structured field includes the subfield nested within it. 2.3 SNMP PDUs From the point of view of the SNMP TPs, the actual SNMP PDUs being sent are just data, which the TPs never examine. With a very few exceptions, the PDUs themselves are ordinary SNMP operations and responses, encoded in the usual way. In particular, character data in an SNMP PDU is still encoded as ASCII characters, even though the character set used by the SNA APPC components that transport the PDU is EBCDIC. For SNMPv1, the only departure from ordinary SNMP is the use of 0.0.0.0 as the origin IP address for a trap. Just as with SNMP over AppleTalk (RFC 1419) and SNMP over IPX (RFC 1420), this value indicates to a manager application that it must identify the sender of the trap based on information it gets from the entity that provided transport services for the trap. In the case of SNMP over SNA, this additional information will be the network-qualified LU name and the TP name of the trap sender. For SNMPv2, the following transport mapping is specified: Moore [Page 5] RFC xxxx SNMP over SNA April 1995 SNMPsnaDefinitions DEFINITIONS ::= BEGIN IMPORTS enterprises FROM RFC1155-SMI MODULE-IDENTITY, OBJECT-IDENTITY FROM SNMPv2-SMI TEXTUAL-CONVENTION FROM SNMPv2-TC; snmpSNAdefinitions MODULE-IDENTITY LAST-UPDATED "9504240000Z" ORGANIZATION "IBM Corporation" CONTACT-INFO " Bob Moore Postal: 800 Park Offices Drive E87/B664 P.O. Box 12195 Research Triangle Park, NC 27709 USA Tel: +1 919 254 4436 Fax: +1 919 254 5483 E-mail: remoore@ralvm6.vnet.ibm.com" DESCRIPTION "The transport mapping for SNMP over SNA." REVISION "9504240000Z" DESCRIPTION "The initial revision of this MIB module was published to the AIW as the document SNMPSNA.TXT." ::= { architectureModules 2 } ibm OBJECT IDENTIFIER ::= { enterprises 2 } ibmArchitecture OBJECT IDENTIFIER ::= { ibm 5 } architectureModules OBJECT IDENTIFIER ::= { ibmArchitecture 16 } snmpSNADomain OBJECT-IDENTITY STATUS current DESCRIPTION "The SNMPv2 over SNA transport domain. The corresponding transport address is of type SnmpSNAAddress." ::= { ibmArchitecture 14 } SnmpSNAAddress ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "Represents an SNA APPC NetId.LuName.TpName. Moore [Page 6] RFC xxxx SNMP over SNA April 1995 For an SnmpSNAAddress of length m: octets contents encoding 1 length of LuName n as an unsigned integer, 3 <= n <= 17 2..(n+1) LuName in the form NetId.LuName, 1-8 octets for NetId from EBCDIC character set 01134-00500, '.' as separator, 1-8 octets for LuName from EBCDIC character set 01134-00500 n+2 length of TpName p as an unsigned integer, 1 <= p <= 64 (n+3)..m TpName TpName, in one of two formats: If octet[n+3] < X'40', 1-4 octets, with all octets after the first belonging to EBCDIC character set 01134-00500 If octet[n+3] >= X'40', 1-64 characters from EBCDIC character set 00640-00500 Default registered TP names: SNMP requests: X'23F0F0F3'(SNMP manager)-->X'23F0F0F4'(SNMP agent) SNMP traps: X'23F0F0F6'(SNMP agent)-->X'23F0F0F5'(SNMP manager) Recommended form for unregistered TP names: SNMP_PORT_ppppp[_ccc...ccc] where ppppp denotes a 5-digit decimal port number, encoded in EBCDIC and 0-padded on the left if necessary, and _ccc...ccc denotes an optional EBCDIC character string. Examples: SNMP_PORT_01234_testing, SNMP_PORT_01234_production. " SYNTAX OCTET STRING (SIZE (6..83)) END The maximum amount of user data that an APPC application program can count on being able to send at once is 32K - 1 bytes. Depending on the length of the sender's TP name, the other fields in the X'1222' GDS can take up to 4 + 70 + 4 = 78 bytes. Thus SNMP PDUs up to length 32K - 79 bytes can reliably be accommodated. 3.0 SNMP over SNA in an APPN Network There are two points at which the design for SNMP over SNA has special affinity with APPN networks: Moore [Page 7] RFC xxxx SNMP over SNA April 1995 1. The LUs that support SNMP over SNA in an APPN network are the control point LUs, i.e., the LUs whose names identify the APPN nodes. This is important because these are the names that appear in the APPN topology database, identifying the nodes currently attached to the network.(1) Thus when an SNMP manager monitoring the topology database at an APPN node is informed that a new node has joined the network, it is immediately in a position to direct SNMP operations to that node: the network-qualified name of the LU to which it should direct the operation is the node name it has just learned about, it can use the default TP name SNMP_PORT_00161_registered (encoded as X'23F0F0F4'), and the mode name SNASVCMG can be tried first. If communications cannot be established using this mode name, then the manager can fall back to the mode name #INTER. 2. APPC sessions with SNMP over SNA's default mode name SNASVCMG are already used in APPN, and are thus likely to be already established when an SNMP manager or agent has something it wishes to send. In addition, the two functions that already use these sessions have traffic patterns that coexist well with the datagram-style communications between the two pairs of SNMP transaction programs. o APPC's Change Number of Sessions (CNOS) A CNOS conversation remains in place for one exchange between the CNOS TPs: the TP assuming the client role requests that the number of sessions between a pair of LUs for a particular mode name be changed to a specified value. The TP assuming the server role returns a response indicating whether the request has been accepted or rejected. o SNA/Management Service's Multiple Domain Support (MDS) MDS involves a pair of one-way TPs: each LU that supports MDS has a registered TP MDS_RECEIVE that is the target of requests to establish conversations, and an unregistered TP MDS_SEND that originates the requests. Responses to MDS requests are returned to MDS_RECEIVE at the LU that originated the request, even though the request was sent out by MDS_SEND. Correlation of --------------- (1) Actually there is a two-level hierarchy of nodes in APPN. The topology database that is replicated at every network node in a well-defined portion of the network termed a topology subnet contains the names of all of the APPN network nodes in the subnet. Thus a manager can detect additions and removals of network nodes by monitoring topology at a single node in each subnet. To detect APPN end nodes, a manager must monitor the local topology of a network node to which an end node is directly attached. For this discussion the point is the same for network nodes and end nodes: both are identified by their control point LU names. Moore [Page 8] RFC xxxx SNMP over SNA April 1995 requests and responses is handled by a component at a higher level than the two MDS TPs. An MDS conversation ordinarily remains in place for a single exchange between the TPs: MDS_SEND sends a single MDS message unit (MDS-MU) containing management data to MDS_RECEIVE, and MDS_RECEIVE returns a Confirmed() acknowledging receipt of the MDS-MU. In addition to using short-lived conversations, the CNOS and MDS TPs have the characteristic of ordinarily having very little traffic to send at all. Thus there is a good fit between them and the SNMP over SNA TPs: all three sets of TPs can share the same SNASVCMG sessions in an APPN network, and still achieve the response times and bandwidth they require, 4.0 Overview of the CPI-C TPs for SNMP over SNA The send and receive logic for all four TPs are the same except for the TP names used and the code that actually acts upon the received X'1222' GDS. The sending side formats the SNMP information into a X'1222' GDS and then does an allocate, send_data, deallocate sequence to the appropriate destination TP. The destination TP (on the receiving side) accepts the conversation and then receives the X'1222' GDS and the deallocate indicator. The GDS is passed to the appropriate SNMP function for actual processing. See below for CPI-C 2.0 pseudo-code samples for both sending and receiving. The pseudo-code takes a drastic approach to error conditions, in that any error is treated as cause to abort the attempted delivery. An intelligent implementation could recover from many conditions. For example, a CM_RESOURCE_FAILURE_RETRY return code on Allocate could be retried with a reasonable chance of success. 4.1 Sending Side Precondition: Side Information entries are used to set the destination TP name and mode name. However, an implementation is free to use CPI-C set calls to set these values. Input: Side_Info, Dest_LU, SNMP_GDS Code: Initialize_Conversation(conv_id, Side_Info, rc); if rc<>CM_OK then abort(); // Override CPI-C default characteristic values // Other characteristics should use the defaults. Moore [Page 9] RFC xxxx SNMP over SNA April 1995 // Must be a basic conversation Set_Conversation_Type(conv_id, CM_BASIC_CONVERSATION, rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // No security tokens Set_Conversation_Security_Type(conv_id, CM_SECURITY_NONE, rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // Send deallocate with data Set_Deallocate_Type(conv_id, CM_DEALLOCATE_FLUSH, rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // Done with overrides // Set the destination LU Set_Partner_LU_Name(conv_id, Dest_LU, length(Dest_LU), rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // Start the conversation Allocate(conv_id, rc) if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // Have deallocate processing done with send_data Set_Send_Type(conv_id, CM_SEND_AND_DEALLOCATE, rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // Send the GDS Send_Data(conv_id, SNMP_GDS, length(SNMP_GDS), contrl_info_rcvd, rc); if rc<>CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; // All done... return(0); 4.2 Receive Side // Assume that this is started as a result of an inbound // attach for one of the SNMP over SNA TPs. If an // implementation wants to prestart this receive logic, // then it will need to use a combination of // Specify_Local_TP_Name and Initialize_For_Incoming calls. // // Accept the conversation Accept_Conversation(conv_id, rc) if rc<>CM_OK then abort(); // Get the partner LU name so the SNMP code can direct the // answer back to the originator. // Note: This is not actually needed by two of the four tps. Extract_Partner_LU_Name(conv_id, Partner_LU, Partner_LU_len, rc); if rc<> CM_OK then {Cancel_Conversation(conv_id, rc); abort() }; Moore [Page 10] RFC xxxx SNMP over SNA April 1995 // The following Receive may need to be replaced with a loop, if the // implementation wants to do either Receive_Immediate or wants to // provide a buffer less than 32K. This pseudo_code assumes that // the receive_type is CM_RECEIVE_AND_WAIT and that the provided // buffer is 32K bytes long. Receive(conv_id, buffer, 32767, data_received, recv_len, status, cntrl_info, rc); if rc<>CM_OK and rc<>CM_DEALLOCATE_NORMAL then {Cancel_Conversation(conv_id, rc); abort() }; if data_received<>CM_COMPLETE_DATA_RECEIVED then {Cancel_Conversation(conv_id, rc); abort() }; // Ensure deallocate was received if rc<>CM_DEALLOCATE_NORMAL then { Receive(conv_id, NULL, 0, data_received, tmp_r_len, status, cntrl_info, rc); if rc<>CM_DEALLOCATE_NORMAL then { Cancel_Conversation(conv_id, rc); abort() } } // At this point we have a complete record and a clean deallocate of // the conversation. // route buffer (i.e., the X'1222' GDS variable) and the partner LU name // to the SNMP code to process this request. return(buffer, recv_len, partner_LU, partner_LU_len); 5.0 References 1. CPI-C 2.0 Specification (1994), IBM order number SC31-6180-01. Moore [Page 11] RFC xxxx SNMP over SNA April 1995 6.0 Author's Address Robert E. Moore IBM Networking Systems P. O. Box 12195 Research Triangle Park, NC 27709 US Phone: +1 919 254 4436 Email: remoore@ralvm6.vnet.ibm.com Moore [Page 12]